The xpander.ai SDK is a comprehensive Backend-as-a-Service (BaaS) platform for building, deploying, and managing AI agents at scale. It provides five core modules that work together to create powerful AI agent applications.
This is the Python SDK documentation. The SDK has been completely refactored to provide a modular, Backend-as-a-Service architecture for enterprise AI agent development.

​
Core Architecture

The SDK is built around five main modules:

Backend

Agents Backend - Get framework specific arguments for AI agents.

Agents

Agent Management - Create, configure, and manage AI agents with tools, knowledge bases, and execution capabilities.

Tasks

Task Execution - Handle complex task workflows, execution management, and real-time streaming.

Tools Repository

Tools Integration - Register local tools, manage external integrations, and handle MCP servers.

Knowledge Bases

Knowledge Management - Create and search knowledge repositories with semantic search capabilities.

Events

Event Handling - Event-driven programming with decorators, real-time streaming, and background processing.

​
Installation

pip install xpander-sdk

# With optional dependencies
pip install xpander-sdk[agno]  # For Agno framework support
pip install xpander-sdk[dev]   # For development

from xpander_sdk import Agents, Tasks, ToolsRepository, KnowledgeBases

# SDK automatically uses environment variables
# Set XPANDER_API_KEY and XPANDER_ORGANIZATION_ID

# Initialize modules directly
agents = Agents()
tasks = Tasks()
tools = ToolsRepository()
knowledge = KnowledgeBases()

​
Key Features

  • 🤖 Agent Management: Create, configure, and manage AI agents with comprehensive lifecycle control
  • ⚡ Task Execution: Handle complex multi-step workflows with real-time event streaming
  • 🔧 Tools Integration: Register local tools and integrate with external services via MCP
  • 📚 Knowledge Bases: Semantic search across document repositories with AI-powered insights
  • 🎯 Event-Driven: Event handling with decorators for responsive agent applications
  • 🔄 Async/Sync Support: Both asynchronous and synchronous interfaces for flexibility
  • 📊 Real-time Monitoring: Track agent performance, metrics, and execution in real-time
  • 🏗️ Modular Architecture: Five independent modules that work seamlessly together

​
Quick Start Example

​
Asynchronous Usage

from xpander_sdk import Agents

# Initialize modules (automatically uses environment variables)
agents = Agents()

# List all agents
agent_list = await agents.alist()

# Load a specific agent
agent = await agents.aget("agent-id")

# Create and execute a task
task = await agent.acreate_task(
    prompt="Analyze this data",
    file_urls=["https://example.com/data.csv"],
    events_streaming=True
)

# Stream task events
async for event in task.aevents():
    print(f"Event: {event.type} at {event.time}")
    if event.type == "task_finished":
        print(f"Result: {event.data.result}")
        break

​
Synchronous Usage

from xpander_sdk import Agents

# Initialize modules
agents = Agents()

# List all agents
agent_list = agents.list()

# Load a specific agent
agent = agents.get("agent-id")

# Create and execute a task
task = agent.create_task(
    prompt="Analyze this data",
    file_urls=["https://example.com/data.csv"]
)

# Check task status
print(f"Task Status: {task.status}")
print(f"Task Result: {task.result}")

​
Event-Driven Development

The SDK supports event-driven programming with decorators for task handling and lifecycle management:

​
Asynchronous Usage

from xpander_sdk import on_task, Events

# Define task handler using decorator
@on_task
async def handle_task(task):
    print(f"Processing task: {task.id}")
    
    # Your custom logic here
    task.result = "Task processed successfully"
    return task

# Start event listener
events = Events()
await events.start(on_execution_request=handle_task)

​
Synchronous Usage

from xpander_sdk import on_task

# Define task handler using decorator
@on_task
def handle_task(task):
    print(f"Processing task: {task.id}")
    
    # Your custom logic here
    task.result = "Task processed successfully"
    return task

​
Lifecycle Management

from xpander_sdk import on_boot, on_shutdown, on_task

# Initialize resources before task processing
@on_boot
async def initialize_resources():
    print("Setting up database and cache...")
    # Initialization logic here

# Handle tasks with initialized resources
@on_task
async def process_task(task):
    print(f"Processing task: {task.id}")
    task.result = "Task completed"
    return task

# Clean up during shutdown
@on_shutdown
async def cleanup_resources():
    print("Cleaning up resources...")
    # Cleanup logic here

​
Module Documentation

Agents Module

Agent creation, management, and execution with tools and knowledge bases

Tasks Module

Task lifecycle management, execution control, and real-time streaming

Tools Repository

Local tool registration, external integrations, and MCP server management

Knowledge Bases

Document management and semantic search across knowledge repositories

Events Module

Event-driven programming, decorators, and background task processing

Configuration

SDK configuration, authentication, and environment setup

Types

Data types, enumerations, and models used across the SDK

​
Authentication

The SDK supports multiple authentication methods:

​
Error Handling

from xpander_sdk.exceptions import ModuleException

try:
    agent = await agents.aget("invalid-agent-id")
except ModuleException as e:
    print(f"Error {e.status_code}: {e.description}")

​
Additional Resources

Getting Started

Begin building with xpander.ai

Tutorials

Step-by-step guides and examples

GitHub Repository

View source code and contribute